home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_100 / 183_01 / comsup.doc < prev    next >
Text File  |  1984-06-21  |  17KB  |  581 lines
  1.         =================================================
  2.         =                            =
  3.         = Communications support for DeSmet C compiler  =
  4.         =                            =
  5.         =================================================
  6.  
  7.  
  8.       Written by Tom Poindexter  (70040,1223), March 1984
  9.  
  10.  
  11. Acknowledgements:   Vern Buerg - for an example of comm support for
  12.                  the Lattice C compiler. (DRIVER.ASM)
  13.             Curt Klinsing - the author listed in DRIVER.ASM
  14.             Earl Terwilliger Jr. - referring me to the PC Tech
  15.                  Journal series on 8088 interrupts
  16.             Chris Dunford - author of the 2 part series in PC Tech
  17.                  Journal (12/83 & 1/84).
  18.  
  19. =========
  20.  
  21. The following files constitute the communication support routines.
  22.  
  23. COMMSUPP.C - The actual C interface routines.
  24.  
  25. COMMASM.A  - Internal assembler routines used by commsupp.c.
  26.  
  27. COMMSUPP.H - An #include file containing declares and defines for
  28.          an application program using commsupp.c.
  29.  
  30. COMMSUPP.DOC - This documentation.
  31.  
  32. -------------
  33.  
  34. COMMTERM.C  - Optional, an example C communications program using
  35.           commsupp.c
  36.  
  37. =========
  38.  
  39.  
  40.    COMMSUPP provides interrupt driven buffered communication support for the
  41. DeSmet C compiler.  Features: XON/XOFF support, two ports active
  42. concurrently, modem break signal generation, status reporting, and
  43. event trapping.
  44.  
  45.    Most of the routines are written in C so that it may be possible to
  46. port these routines to another compiler.  The assembler language routines
  47. are coded in DeSmet ASM88 syntax, which is somewhat different than the
  48. IBM Macro Assembler syntax.
  49.  
  50.    DeSmet library functions that may or may not be available on other
  51. compilers are:
  52.  
  53.   _lmove(num_bytes,source_offset,source_segment,target_offset,target_segment);
  54.  
  55.     Performs a memory move using REP MOVSB so that overlapping moves are
  56.     handled correctly (processor direction flag set correctly).
  57.  
  58.   _move(num_bytes,source_offset,target_offset);
  59.  
  60.     Similiar to _lmove, except that the move is within the C data segment.
  61.  
  62.   c_ds = _showds();
  63.  
  64.     Returns the C data segment.
  65.  
  66.   c_cs = _showcs();
  67.  
  68.     Returns the C program segment.
  69.  
  70.   ptr = malloc(num_bytes);
  71.  
  72.     Allocate a specific number of bytes in memory and return a pointer
  73.     to the area.
  74.  
  75.  
  76. The following functions are not available in DeSmet C, but may or may not
  77. be included in other compilers.  These routines are in COMMASM.A:
  78.  
  79.   struct { int ax,bx,cx,dx,si,di,ds,es;} in_regs,out_regs;
  80.   flags = sysint (interrupt, &in_regs, &out_regs);
  81.  
  82.     Call a system interrupt routine, passing and returning register values.
  83.  
  84.   value = inb(hardware_port);
  85.  
  86.     Input a byte value from a hardware port address.
  87.  
  88.   outb(hardware_port,value);
  89.  
  90.     Output a byte value to a hardware port address.
  91.  
  92.    cli();
  93.  
  94.      Disable system interrupts (CLI).
  95.  
  96.    sti();
  97.  
  98.      Enable system interrupts (STI);
  99.  
  100.  
  101.  
  102. DeSmet C compiler use
  103. =====================
  104.  
  105.   1. Compile COMMSUPP.C with C88
  106.      A>c88 commsupp
  107.  
  108.   2. Assemble COMMASM.A with ASM88
  109.      A>asm88 commasm
  110.  
  111.   3. If you maintain your own library, use LIB88 to add commsupp and commasm
  112.      A>lib88 commasm commsupp -oyourlib
  113.  
  114.   4. Create and compile your program.  #include "commsupp.h".
  115.      A>c88 yourprog
  116.  
  117.   5. Bind your program with your library (as in #3) or with the object
  118.      modules alone.
  119.      A>bind yourprog (your-other-modules) commsupp commasm     w/o private lib
  120.      A>bind yourprog yourlib.s                       w/  private lib
  121.  
  122.  
  123.  
  124.  
  125. Description of routines:
  126. ========================
  127.  
  128. init_com  -  Initializes the serial port, enables and sets interrupt vectors,
  129.          sets communication parameters (baud, parity, data length,
  130.          stop bits), and allocates a receive buffer.
  131.  
  132.      Parms:
  133.        port: 1 = com1:, 2 = com2:
  134.        baud: 110, 150, 300, 450, 600, 1200, 2400, 4800, 9600
  135.        parity: 0 = none, 1 = odd, 2 = even, 3 = mark, 4 = space
  136.        data: 5, 6, 7, 8
  137.        stop: 1, 2
  138.        buff_len: length of receive buffer up to 32767 bytes
  139.  
  140.      Returns:
  141.        ERROR (-1): comm port not available or invalid parm
  142.        TRUE (1): ok
  143.  
  144.      Example:
  145.  
  146.        int port, baud, parity, data, stop, buff_len;
  147.  
  148.        port = 1;
  149.        baud = 300;
  150.        parity = 0;
  151.        data = 8;
  152.        stop = 1;
  153.        buff_len = 1024;
  154.  
  155.        if (init_com(port,baud,parity,data,stop,buff_len) == ERROR)
  156.      puts("\nComm port initialzation failed.\n");
  157.  
  158.      Notes:
  159.        See defines for parity values in COMMSUPP.H.  This function sets the
  160.        8250 modem controller chip and the 8259 interrupt controller chip.
  161.        Also, this routine "pokes" the value of the C data segment into
  162.        the interrupt handler routine so that no matter where the
  163.        interrupt occurs, the interrupt handler will have access to the
  164.        C data segment.
  165.        See the PC Tech Journal (12/83 & 1/84) for details on the
  166.        interrupt controller.
  167.  
  168. =========
  169.  
  170. uninit_com - Disables interrupts, flushes buffer. Optionally leaves serial
  171.          port open.
  172.  
  173.      Parms:
  174.        port: 1 = com1:, 2 = com2:
  175.        lv_open: TRUE (1) = leave serial open (DTR enabled), FALSE (0) = close
  176.         serial port (drop DTR).
  177.  
  178.      Returns:
  179.        ERROR (-1): comm port never intialized or invalid port number.
  180.        TRUE (1): ok
  181.  
  182.      Example:
  183.        int port, lv_open;
  184.  
  185.        port = 1;
  186.        lv_open = TRUE;
  187.  
  188.        uninit_com(port,lv_open);
  189.        puts("\n\nProgram terminating.......Comm port left open.\n\n");
  190.  
  191.      Notes:
  192.        It is VERY important that this function is successfully completed
  193.        prior to the termination of the user program.  Otherwise, any incoming
  194.        chars will trigger the interrupt and control will pass to the interrupt
  195.        handler address, whether or not there is a valid routine to process
  196.        the interrupt.
  197.  
  198. =========
  199.  
  200. send_brk - Send a break signal to the specified port.  1/2 second of mark
  201.        signal is generated.
  202.  
  203.      Parms:
  204.        Port: 1 = com1:, 2 = com2:
  205.  
  206.      Returns:
  207.        ERROR (-1): comm port never intialized or invalid port number.
  208.        TRUE (1): ok
  209.  
  210.      Example:
  211.        int port;
  212.  
  213.        port = 1;
  214.        send_brk(port);
  215.  
  216.      Notes:
  217.        See this routine in commsupp.c on using the SYSINT function.  The
  218.        time-of-day interrupt (documented in the tech reference) is invoked
  219.        to return the current time-of-day tick count.  The effect of the
  220.        routine is a delay for a specified time that is independent
  221.        of processor speed.
  222.  
  223. =========
  224.  
  225. set_xoff - Enables or disables the XON/XOFF protocol.  See companion functions
  226.        recd_xoff and sent_xoff.  If enabled, an XOFF received will set
  227.        a flag which can be parsed with the recd_xoff function.  The user
  228.        program must check recd_xoff to suspend transmission, i.e.,
  229.        outp_char and outp_strn are not automatically suspended.  Also, if
  230.        the receive buffer becomes 75% full, an XOFF is sent to the remote
  231.        computer, and a flag is set, which can be parsed with sent_xoff.
  232.  
  233.      Parms:
  234.        port: 1 = com1:, 2 = com2:
  235.        state: TRUE (1) = XON/XOFF enabled, FALSE (0) = XON,XOFF disabled
  236.  
  237.      Returns:
  238.        ERROR (-1): comm port never intialized or invalid port number.
  239.        TRUE (1): ok
  240.  
  241.      Example:
  242.        int port, state;
  243.  
  244.        port = 1;
  245.        puts("\nDo you want XON/XOFF enabled (y/n) ? ");
  246.        state = (getchar() == 'y') ? TRUE : FALSE;
  247.        set_xoff(port,state);
  248.  
  249.      Notes:
  250.        XON/XOFF should be disabled anytime binary transmissions are performed,
  251.        i.e., all 8 bits significant.  When XON/XOFF is disabled, there is no
  252.        mechansism to prevent or report buffer overrun.    In this case the
  253.        user program should be alert to the number of bytes in the buffer using
  254.        the inp_cnt function.
  255.  
  256. =========
  257.  
  258. recd_xoff - Report if an XOFF character has been received.  If TRUE, then
  259.         also reset the recd_xoff flag to FALSE.
  260.  
  261.      Parms:
  262.        port: 1 = com1:, 2 = com2:
  263.  
  264.      Returns:
  265.        ERROR (-1): comm port never intialized or invalid port number.
  266.        TRUE (1): XOFF has been received
  267.        FALSE (0): XOFF has not